<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
 <HEAD>
  <TITLE>Apache module mod_status</TITLE>
 </HEAD>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY
 BGCOLOR="#FFFFFF"
 TEXT="#000000"
 LINK="#0000FF"
 VLINK="#000080"
 ALINK="#FF0000"
>

<!--#include virtual="header.html" -->
<H1 ALIGN="CENTER">Module mod_status</H1>

The Status Module is only available in Apache 1.1 and later.<P>

<H2>Function</H2>

The Status module allows a server administrator to find out how well
their server is performing.  A HTML page is presented that gives
the current server statistics in an easily readable form.  If required
this page can be made to automatically refresh (given a compatible
browser).  Another page gives a simple machine-readable list of the current
server state.
<P>
The details given are:
<UL>
<LI>The number of children serving requests
<LI>The number of idle children
<LI>The status of each child, the number of requests that child has
performed and the total number of bytes served by the child (*)
<LI>A total number of accesses and byte count served (*)
<LI>The time the server was started/restarted and the
time it has been running for
<LI>Averages giving the number of requests per second,
the number of bytes served per second and the average number
of bytes per request (*)
<LI>The current percentage CPU used by each child and in total by
Apache (*)
<LI>The current hosts and requests being processed (*)
</UL>

A compile-time option must be used to display the details marked "(*)" as
the instrumentation required for obtaining these statistics does not
exist within standard Apache.

<H2>Enabling Status Support</H2>

To enable status reports only for browsers from the foo.com
domain add this code to your <CODE>access.conf</CODE> configuration file
<PRE>
    &lt;Location /server-status&gt;
    SetHandler server-status

    order deny,allow
    deny from all
    allow from .foo.com
    &lt;/Location&gt;
</PRE>
<P>
You can now access server statistics by using a Web browser to access the
page <CODE>http://your.server.name/server-status</CODE>
<P>
Note that mod_status will only work when you are running Apache in
<A HREF="core.html#servertype">standalone</A> mode and not
<A HREF="core.html#servertype">inetd</A> mode.

<H3>Automatic Updates</H3>
You can get the status page to update itself automatically if you have
a browser that supports "refresh".  Access the page
<CODE>http://your.server.name/server-status?refresh=N</CODE> to refresh the
page every N seconds.
<H3>Machine Readable Status File</H3>
A machine-readable version of the status file is available by accessing the
page <CODE>http://your.server.name/server-status?auto</CODE>.  This is useful
when automatically run, see the Perl program in the <CODE>/support</CODE>
directory of Apache, <CODE>log_server_status</CODE>.

<H2>Full Instrumentation</H2>

To obtain full statistics you must compile Apache with a special
directive.  On some machines there may be a small performance loss
if you do this.  Try full statistics and see if you notice any
difference.  If you do please contact <A HREF="mailto:mark@ukweb.com">
mark@ukweb.com</A> and tell me your configuration.

<P>

Do this by adding the following to the AUX_CFLAGS line in the
"Configuration" file and then recompiling as usual.
<PRE>
        AUX_CFLAGS= (something) -DSTATUS
</PRE>

<BLOCKQUOTE>
 <STRONG>
  It should be noted that if <SAMP>mod_status</SAMP> is compiled into
  the server, its handler capability is available in <EM>all</EM>
  configuration files, including <EM>per</EM>-directory files
  (<EM>e.g.</EM>, <SAMP>.htaccess</SAMP>).  This may have
  security-related ramifications for your site.
 </STRONG>
</BLOCKQUOTE>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>
